whatsapp Trigger webhookInstall

Overview

This node acts as a webhook trigger for WhatsApp integrations in n8n. It listens for incoming HTTP GET and POST requests at a specified path, typically from the WhatsApp Business API (Meta). The node is designed to:

• Validate webhook setup requests from Meta (GET).
• Receive and process incoming WhatsApp messages or status updates (POST).
• Optionally download and attach images sent via WhatsApp.
• Route different types of events (validation, message, status, invalid phone) to separate outputs.

Common scenarios:

• Automating workflows based on incoming WhatsApp messages (e.g., customer support, notifications).
• Handling media (images) sent to your WhatsApp business number.
• Validating webhook endpoints with Meta during setup.

Practical examples:

• Triggering an n8n workflow when a customer sends a WhatsApp message.
• Saving received images to cloud storage.
• Sending automated replies or forwarding messages to other systems.

Properties

Output

The node has four output branches, each corresponding to a specific event type:

1. Validate (Webhook validation):
   • On GET requests for webhook verification, outputs:

     {
       "query": { ... } // The query parameters received (including hub.mode, hub.challenge, etc.)
     }
     

2. Message (Incoming WhatsApp message):
   • On valid POST requests with a matching phone number ID:
     • If the message contains an image:
       • Outputs a binary field:

         {
           "message": { ... }, // Full request body
           "binary": {
             "data": {
               "data": "<base64-encoded image>",
               "fileName": "image",
               "mimeType": "<MIME type>"
             }
           }
         }
         

     • Otherwise:
       • Outputs:

         {
           "message": { ... } // Full request body
         }
         

3. status (Status update):
   • On POST requests containing status updates:

     {
       "updateMessage": { ... } // The change object from the webhook payload
     }
     

4. InvalidPhone (Invalid phone number):
   • On POST requests where the phone number ID does not match:

     {
       "message": { ... } // Full request body
     }
     

Binary Output:
If the incoming WhatsApp message contains an image, the node downloads the image and attaches it as a base64-encoded binary property (data) with its MIME type and filename.

Dependencies

• External Service: Requires a WhatsApp Business API account and webhook configuration in Meta's developer portal.
• API Key/Credentials: Needs whatsAppApi credentials (with accessToken and businessAccountId).
• n8n Configuration: Webhook URL must be accessible by Meta for validation and message delivery.

Troubleshooting

Common Issues:

• Webhook Validation Fails:

  • Error: "Error token"
    • Cause: The Verify Token provided does not match the one set in Meta's developer portal.
    • Solution: Ensure the "Verify Token" property matches exactly.

• No Messages Received:

  • Cause: Incorrect "Path" or webhook not registered correctly in Meta.
  • Solution: Double-check the webhook URL and ensure it's publicly accessible.

• Image Not Downloaded:

  • Cause: Invalid or expired access token, or missing permissions.
  • Solution: Check WhatsApp API credentials and permissions.

• HTTP 401/403 Errors:

  • Cause: Invalid credentials or insufficient permissions.
  • Solution: Update or reauthorize the WhatsApp API credentials in n8n.

Links and References

• n8n Docs: Webhook Node
• n8n Docs: Respond to Webhook Node
• Meta WhatsApp Business API Webhooks
• n8n WhatsApp Integration Guide